OpenClaw 技能开发完全指南

本文是 OpenClaw 技能开发的系统性教程，从基础概念到高级实践，帮助你创建属于自己的 AI 技能。

概述

OpenClaw 的技能系统（AgentSkills）是其核心扩展机制。通过技能，你可以：

为 AI 助理添加特定领域的能力
封装复杂的工具调用逻辑
实现可复用的最佳实践
构建领域专用的 AI 助手

本指南将带你从零开始，掌握技能开发的完整流程。

一、技能系统架构

1.1 什么是技能

技能是 OpenClaw 中预定义的指令集，用于指导 AI 在特定场景下的行为。每个技能包含：

触发条件：什么情况下激活该技能
执行逻辑：技能激活后的具体操作
工具调用：需要使用的工具及参数
输出格式：结果的呈现方式

1.2 技能目录结构

~/.openclaw/skills/
├── skill-name/
│   ├── SKILL.md          # 技能定义文件（必需）
│   ├── README.md         # 技能说明文档
│   ├── references/       # 参考资料
│   ├── scripts/          # 辅助脚本
│   └── examples/         # 使用示例

1.3 SKILL.md 标准格式

markdown

# Skill: 技能名称

## Description
技能的简短描述，用于匹配用户意图。

## Triggers
- 触发关键词 1
- 触发关键词 2
- 触发场景描述

## Instructions
1. 第一步操作
2. 第二步操作
3. ...

## Tools
- tool_name: 工具使用说明
- another_tool: 参数配置

## Examples
用户：示例问题
助手：示例回答

## Notes
注意事项和边界条件

二、创建第一个技能

2.1 技能规划

在创建技能前，明确以下问题：

解决什么问题？ - 技能的核心价值
谁来使用？ - 目标用户群体
何时触发？ - 激活条件
需要什么工具？ - 依赖的工具能力

2.2 实战案例 1：天气查询技能

让我们创建一个简单的天气查询技能。

步骤 1：创建技能目录

bash

mkdir -p ~/.openclaw/skills/weather-query
cd ~/.openclaw/skills/weather-query

步骤 2：编写 SKILL.md

markdown

# Skill: 天气查询

## Description
为用户提供实时天气信息和 forecasts，支持多地点查询。

## Triggers
- 天气
- 气温
- 预报
- 今天下雨吗
- 明天天气如何
- {地点} 天气

## Instructions
1. 识别用户查询的地点（默认使用用户位置）
2. 确定查询类型（当前天气/预报）
3. 调用 weather 技能获取数据
4. 格式化输出：
   - 当前温度、体感温度
   - 天气状况（晴/雨/云等）
   - 湿度、风力
   - 未来 24 小时趋势
5. 如有极端天气，添加提醒

## Tools
- weather: 使用 wttr.in 或 Open-Meteo API
  - 参数：location, days, format

## Examples
用户：北京天气怎么样？
助手：🌤️ 北京当前天气：
- 温度：22°C（体感 24°C）
- 状况：多云转晴
- 湿度：45%
- 风力：东北风 2 级

未来 24 小时无降水，适宜户外活动。

用户：上海明天会下雨吗？
助手：🌧️ 上海明日预报：
- 上午：小雨，20-23°C
- 下午：中雨，22-25°C
- 降水概率：85%

建议携带雨具，避免户外安排。

## Notes
- 地点识别支持中英文
- 默认查询当前城市
- 极端天气（暴雨/高温/寒潮）需特别提醒
- 数据缓存 10 分钟，避免频繁请求

步骤 3：测试技能

在 OpenClaw 中测试：

用户：深圳天气

验证技能是否正确触发并返回预期结果。

2.3 实战案例 2：文件整理技能

创建一个自动整理下载目录的技能。

SKILL.md 内容：

markdown

# Skill: 文件整理

## Description
自动分类整理指定目录中的文件，按类型移动到对应子目录。

## Triggers
- 整理文件
- 清理下载目录
- 分类文件
- organize files
- tidy up

## Instructions
1. 确认目标目录（默认 ~/Downloads）
2. 扫描目录中的所有文件
3. 按扩展名分类：
   - 图片：jpg, png, gif, webp → Images/
   - 文档：pdf, doc, docx, xls, xlsx → Documents/
   - 代码：js, py, md, json → Code/
   - 压缩包：zip, tar, gz → Archives/
   - 其他 → Misc/
4. 创建目标子目录（如不存在）
5. 移动文件到对应目录
6. 生成整理报告：
   - 总文件数
   - 各类别数量
   - 节省空间（如有删除）
7. 询问是否删除空目录

## Tools
- exec: 执行 shell 命令
  - ls, mkdir, mv, du
- read: 读取文件列表
- write: 生成整理报告

## Examples
用户：整理一下下载目录
助手：📁 开始整理 ~/Downloads...

扫描完成，发现 127 个文件：
- 🖼️ 图片：45 个 → Images/
- 📄 文档：32 个 → Documents/
- 💻 代码：28 个 → Code/
- 📦 压缩包：15 个 → Archives/
- 📋 其他：7 个 → Misc/

整理完成！释放空间 2.3GB。

## Notes
- 移动前检查目标文件是否已存在
- 同名文件添加时间戳后缀
- 隐藏文件（.开头）跳过处理
- 大文件（>1GB）单独确认
- 支持 dry-run 模式预览

2.4 实战案例 3：代码审查技能

创建辅助代码审查的技能。

markdown

# Skill: 代码审查

## Description
对代码进行自动化审查，检查常见问题并提供改进建议。

## Triggers
- 代码审查
- code review
- 检查这段代码
- 有什么优化建议
- 代码质量

## Instructions
1. 接收用户提供的代码（文件路径或代码片段）
2. 识别编程语言
3. 执行静态检查：
   - 语法错误
   - 未使用变量
   - 潜在的空指针
   - 资源泄漏风险
   - 安全漏洞（SQL 注入、XSS 等）
4. 风格检查：
   - 命名规范
   - 注释完整性
   - 代码重复
   - 函数长度
5. 性能建议：
   - 时间复杂度优化
   - 内存使用优化
   - 并发处理建议
6. 生成审查报告：
   - 问题分级（严重/警告/建议）
   - 具体位置（文件：行号）
   - 修复建议
   - 参考代码

## Tools
- read: 读取代码文件
- exec: 调用 linter 工具
  - eslint, pylint, flake8
- write: 生成审查报告
- sessions_spawn: 复杂分析时spawn 子代理

## Examples
用户：帮我审查一下这个 Python 文件
助手：🔍 代码审查报告：main.py

### 严重问题（2）
1. 第 23 行：SQL 注入风险
   - 问题：直接拼接用户输入到 SQL
   - 建议：使用参数化查询
   ```python
   # ❌ 危险
   cursor.execute(f"SELECT * FROM users WHERE id={user_id}")
   
   # ✅ 安全
   cursor.execute("SELECT * FROM users WHERE id=?", (user_id,))

第 45 行：资源未关闭
- 问题：文件打开后未关闭
- 建议：使用 with 语句

警告（3）

第 12 行：未使用的变量 temp_data
第 67 行：函数过长（85 行），建议拆分
第 89 行：缺少类型提示

建议（5）

添加模块文档字符串
统一命名风格（snake_case）
增加单元测试覆盖率
提取魔法数字为常量
添加错误处理

综合评分：B (75/100)

Notes

支持语言：Python, JavaScript, TypeScript, Go, Java
尊重项目现有的代码风格
不阻塞用户操作，仅提供建议
敏感代码（密码、密钥）自动脱敏


---

## 三、高级技能开发

### 3.1 多步骤工作流技能

复杂技能需要协调多个工具和步骤。

**案例：文章发布技能**

```markdown
# Skill: 文章发布

## Description
自动化完成文章从创建到发布的全流程。

## Instructions
1. 验证文章草稿（存在性、格式）
2. 添加 frontmatter（title, date, tags）
3. 更新网站配置文件（侧边栏）
4. 执行构建命令（npm run build）
5. 部署到服务器（rsync/scp）
6. 验证发布结果（HTTP 检查）
7. 更新首页（今日更新区域）
8. 提交到 Git 仓库
9. 发送发布通知

## Tools
- read/write: 文件操作
- exec: 构建、部署命令
- process: 长时间任务管理
- message: 发布通知
- browser: 验证发布结果

## Error Handling
- 每步设置超时（30-120 秒）
- 失败时重试（最多 3 次）
- 保存中间状态支持断点续传
- 关键错误立即通知用户

3.2 条件分支技能

根据运行时条件选择不同执行路径。

markdown

# Skill: 智能回复

## Instructions
1. 分析消息来源：
   - 主会话（direct chat）→ 加载 MEMORY.md
   - 群聊（group chat）→ 不加载私人记忆
   
2. 判断回复类型：
   - 被@或点名 → 必须回复
   - 直接问题 → 必须回复
   - 闲聊 → 选择性回复
   - 已有答案 → 可保持沉默
   
3. 选择回复方式：
   - 简单确认 → emoji 反应
   - 信息性问题 → 文字回复
   - 复杂问题 → spawn 子代理
   - 故事性内容 → TTS 语音

4. 检查时间：
   - 23:00-08:00 → 除非紧急否则静默
   - 用户忙碌状态 → 减少打扰

3.3 状态管理技能

维护跨会话的状态信息。

markdown

# Skill: 任务追踪

## State Storage
- 状态文件：~/.openclaw/workspace/memory/task-state.json
- 格式：
```json
{
  "activeTasks": [
    {
      "id": "task-001",
      "name": "文章发布",
      "status": "in_progress",
      "step": 3,
      "totalSteps": 7,
      "createdAt": 1710835200,
      "updatedAt": 1710836400
    }
  ],
  "completedTasks": [...],
  "failedTasks": [...]
}

Instructions

任务开始时创建状态记录
每完成一步更新状态
会话重启时恢复状态
任务完成时归档
超时任务标记为失败


---

## 四、技能调试与测试

### 4.1 调试技巧

**日志记录**
```markdown
在技能中添加详细日志：

```bash
# 记录技能激活
echo "[$(date)] Skill triggered: $SKILL_NAME" >> ~/.openclaw/logs/skills.log

# 记录关键步骤
echo "[$(date)] Step 3/7: Building website..." >> ~/.openclaw/logs/skills.log

断点测试

bash

# 在关键步骤前暂停
read -p "按回车继续..."

4.2 测试清单

创建技能后，验证以下项目：

[ ] 触发条件准确（不误触发、不漏触发）
[ ] 工具调用正确（参数、权限）
[ ] 错误处理完善（超时、失败重试）
[ ] 输出格式清晰（人类可读）
[ ] 性能合理（无死循环、资源泄漏）
[ ] 边界条件处理（空输入、大文件）
[ ] 与其他技能无冲突

4.3 常见问题排查

问题	可能原因	解决方案
技能不触发	触发词不匹配	检查 Triggers 定义
工具调用失败	权限不足	检查工具权限配置
输出格式错误	模板语法错误	验证 Markdown 格式
执行超时	缺少超时设置	添加 timeout 参数
状态丢失	未保存状态	实现状态持久化

五、技能发布与共享

5.1 技能打包

bash

# 技能目录结构
my-skill/
├── SKILL.md           # 必需
├── README.md          # 推荐
├── package.json       # 元数据（可选）
├── references/        # 参考资料
├── scripts/           # 辅助脚本
└── examples/          # 示例

# package.json 示例
{
  "name": "my-skill",
  "version": "1.0.0",
  "description": "技能描述",
  "author": "作者名",
  "license": "MIT",
  "openclaw": {
    "minVersion": "1.0.0",
    "tools": ["exec", "read", "write"],
    "triggers": ["关键词 1", "关键词 2"]
  }
}

5.2 技能文档

编写清晰的 README.md：

markdown

# 技能名称

## 功能简介
一句话说明技能用途。

## 安装方法
```bash
cp -r my-skill ~/.openclaw/skills/

使用方法

用户：触发词助手：响应示例

配置选项

配置项	默认值	说明
timeout	30s	执行超时
retries	3	重试次数

依赖工具

exec
read
write

已知限制

不支持 Windows
需要网络连接

更新日志

v1.0.0 (2026-03-20) - 初始版本


### 5.3 技能市场（未来）

OpenClaw 计划支持技能共享：

1. **技能仓库** - 官方/社区技能库
2. **评分系统** - 用户评价技能质量
3. **版本管理** - 技能更新与回滚
4. **依赖管理** - 自动安装依赖技能

---

## 六、最佳实践

### 6.1 设计原则

**单一职责**
- 一个技能只做一件事
- 复杂功能拆分为多个技能协作

**明确边界**
- 清晰定义触发条件
- 明确说明不处理的场景

**容错设计**
- 假设所有外部调用都可能失败
- 提供降级方案

**用户友好**
- 错误信息人类可读
- 提供下一步建议

### 6.2 性能优化

**缓存策略**
```markdown
- API 响应缓存（10 分钟）
- 文件列表缓存（5 分钟）
- 配置信息缓存（启动时加载）

并发处理

markdown

- 独立任务并行执行
- 使用 Promise.all 协调
- 限制并发数避免资源耗尽

资源管理

markdown

- 及时关闭文件句柄
- 清理临时文件
- 设置内存使用上限

6.3 安全考虑

输入验证

检查文件路径（防止目录遍历）
验证用户输入（防止注入攻击）
限制操作范围（沙箱环境）

权限控制

最小权限原则
敏感操作需要确认
审计日志记录

数据保护

敏感信息加密存储
不记录密码/密钥
定期清理日志

七、实战项目

7.1 项目 1：智能晨间简报技能

目标：每天早上自动生成个性化简报

功能：

天气信息
日历事件
未读邮件摘要
新闻头条
待办事项提醒

实现步骤：

创建技能目录
定义触发条件（每天 08:00 或用户请求）
调用各数据源工具
格式化输出为 Markdown
通过消息发送给用户

7.2 项目 2：Git 工作流助手技能

目标：简化日常 Git 操作

功能：

状态检查（git status 解读）
提交建议（根据变更生成 commit message）
分支管理（创建/合并/删除）
冲突解决（智能合并建议）
远程同步（push/pull 状态报告）

实现步骤：

封装常用 Git 命令
解析命令输出为人类语言
添加安全确认（destructive operations）
集成到日常开发流程

7.3 项目 3：学习进度追踪技能

目标：帮助追踪学习目标和进度

功能：

目标设定（SMART 原则）
进度记录（每日学习时长）
成就系统（里程碑奖励）
复习提醒（间隔重复）
数据分析（学习趋势图表）

实现步骤：

设计数据结构（目标、进度、成就）
实现状态持久化（JSON 文件）
创建定时任务（每日提醒）
生成可视化报告

八、总结

核心要点

技能是 OpenClaw 的扩展核心 - 通过技能定制 AI 行为
SKILL.md 是技能定义标准 - 遵循格式确保兼容性
从简单开始 - 先实现核心功能，再添加高级特性
重视错误处理 - 健壮的技能才能长期使用
文档即代码 - 清晰的文档降低使用门槛

下一步

尝试创建第一个简单技能
阅读现有技能源码学习
参与社区技能开发
贡献技能到官方仓库

资源链接

🟢🐉 开始你的技能开发之旅吧！

OpenClaw 技能开发完全指南 ​

概述 ​

一、技能系统架构 ​

1.1 什么是技能 ​

1.2 技能目录结构 ​

1.3 SKILL.md 标准格式 ​

二、创建第一个技能 ​

2.1 技能规划 ​

2.2 实战案例 1：天气查询技能 ​

2.3 实战案例 2：文件整理技能 ​

2.4 实战案例 3：代码审查技能 ​

警告（3） ​

建议（5） ​

Notes ​

3.2 条件分支技能 ​

3.3 状态管理技能 ​

Instructions ​

4.2 测试清单 ​

4.3 常见问题排查 ​

五、技能发布与共享 ​

5.1 技能打包 ​

5.2 技能文档 ​

使用方法 ​

配置选项 ​

依赖工具 ​

已知限制 ​

更新日志 ​

6.3 安全考虑 ​

七、实战项目 ​

7.1 项目 1：智能晨间简报技能 ​

7.2 项目 2：Git 工作流助手技能 ​

7.3 项目 3：学习进度追踪技能 ​

八、总结 ​

核心要点 ​

下一步 ​

资源链接 ​

OpenClaw 技能开发完全指南

概述

一、技能系统架构

1.1 什么是技能

1.2 技能目录结构

1.3 SKILL.md 标准格式

二、创建第一个技能

2.1 技能规划

2.2 实战案例 1：天气查询技能

2.3 实战案例 2：文件整理技能

2.4 实战案例 3：代码审查技能

警告（3）

建议（5）

Notes

3.2 条件分支技能

3.3 状态管理技能

Instructions

4.2 测试清单

4.3 常见问题排查

五、技能发布与共享

5.1 技能打包

5.2 技能文档

使用方法

配置选项

依赖工具

已知限制

更新日志

6.3 安全考虑

七、实战项目

7.1 项目 1：智能晨间简报技能

7.2 项目 2：Git 工作流助手技能

7.3 项目 3：学习进度追踪技能

八、总结

核心要点

下一步

资源链接